/**
 *  TransactionsLog.java        22-ott-2009
 *   
 * Copyright (c) 2009 mentalsmash.org
 *  
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 * 
 *  http://www.apache.org/licenses/LICENSE-2.0
 * 
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 * 
 *  The use of the Apache License does not indicate that this project is
 *  affiliated with the Apache Software Foundation.
 */

package org.mentalsmash.tazio.transactions.log;

import java.util.List;

import org.mentalsmash.tazio.transactions.Transaction;
import org.mentalsmash.tazio.transactions.TransactionStatus;
import org.mentalsmash.tazio.transactions.identifiers.TID;
import org.mentalsmash.tazio.transactions.management.TazioTransaction;

/**
 * An instance of <tt>BasicTransactionLogManager</tt> keeps track of
 * transactions in the local system.
 * <p>
 * Whenever a transactions enters in the systems (either because it is locally
 * started or because it is received for validation) the log has to keep track
 * of that transaction and record it, until its retention has no longer meaning
 * for the system.
 * </p>
 * 
 * @author Andrea Reale
 * @version 0.0.1
 */
public interface TransactionsLog {
    /**
     * Returns a reference to the {@link Transaction} object that was the last
     * to commit locally to the system.
     * 
     * @return the last committed transaction or <code>null</code> if no
     *         transaction was committed in the system
     */
    TazioTransaction getLastCommitted();

    /**
     * Returns a List of {@link Transaction} objects that are currently active
     * in the system.
     * <p>
     * A transaction is said to be active if it is not in one of the following
     * states:
     * <ul>
     * <li>FLOATING</lI>
     * <li>COMMITTED</li>
     * <li>ROLLED_BACK</li>
     * </ul>
     * </p>
     * 
     * @return a List of {@link Transaction} objects that are currently active
     *         in the system, ordered by ascending <code>seqNo</code>
     */
    List<TazioTransaction> getActive();

    /**
     * Returns a committed transaction having final sequence number <code>
	 * seqNo</code>
     * . If no such transaction is fund returns <code>null</code>
     * 
     * @param seqNo
     *            The sequence number of the committed transaction to retrieve
     * @return the committed transaction having the given <code>seqNo</code>
     */
    TazioTransaction getCommittedTx(long seqNo);

    /**
     * Returns active transactions in the log having a sequence number
     * <code>seqNo</code> greater then <code>fromSeqNo</code> and
     * <strong>equal</strong> or smaller then <code>toSeqNo</code>
     * 
     * @param fromSeqNo
     *            represents the lower bound to the sequence number of the
     *            transactions returned in the list. If -1 returns from the
     *            first transaction in the log. Notice that the returned list
     *            will not contain transaction having sequence number equal to
     *            <code>fromSeqNo</code>.
     * @param toSeqNo
     *            represents the upper bound on the transactions returned in the
     *            list: every transaction returned will have a sequence number
     *            that is smaller then or equal to the value of this parameter.
     *            A value of -1 means that this method will return transactions
     *            till the end of the log, last included.
     * @return a List of active transactions having <code>seqNo</code> inside
     *         the given range, ordered by <code>seqNo</code>
     */
    List<TazioTransaction> getActive(long fromSeqNo, long toSeqNo);

    /**
     * Returns committed transactions in the log having a sequence number
     * <code>seqNo</code> greater or equal to <code>fromSeqNo</code> and
     * <strong>strictly</strong> smaller then <code>toSeqNo</code>
     * 
     * @param fromSeqNo
     *            represents the lower bound to the sequence number of the
     *            transactions returned in the list. If -1 returns from the
     *            first transaction in the log. Notice that the returned list
     *            will not contain transaction having sequence number equal to
     *            <code>fromSeqNo</code>.
     * @param toSeqNo
     *            represents the upper bound on the transactions returned in the
     *            list: every transaction returned will have a sequence number
     *            that is smaller then or equal to the value of this parameter.
     *            A value of -1 means that this method will return transactions
     *            till the end of the log, last included.
     * @return a List of committed transactions having <code>seqNo</code> inside
     *         the given range, ordered by <code>seqNo</code>
     */
    List<TazioTransaction> getCommitted(long fromSeqNo, long toSeqNo);

    /**
     * Returns a list containing the history of recently committed transactions
     * in the system.
     * <p>
     * Notice there is no guarantee on how long a committed transaction is kept
     * in the log.
     * </p>
     * 
     * @return a list containing the history of recently committed transactions
     *         in the system, ordered by <code>seqNo</code>
     */
    List<TazioTransaction> getCommitted();

    /**
     * Returns the status of a transaction having the given <code>tid</code> if
     * available in the log. Otherwise it returns <code>null</code>
     * 
     * @param tid
     *            the transaction identifier of the transaction to return.
     * @return the status of the transaction having the given <code>tid</code>,
     *         otherwise it returns null
     */
    TransactionStatus getStatusByTID(TID tid);

    /**
     * Returns a transaction having the given <code>tid</code> if available in
     * the log. Otherwise it returns <code>null</code>.
     * <p>
     * Notice that this method may return null even if the outcome of a given
     * transaction is still saved in the log: if you need to know only the
     * outcome of a transaction use {@link #getStatusByTID(TID)} instead.
     * </p>
     * 
     * @param tid
     *            the transaction identifier of the transaction to return.
     * @return a transaction having the given <code>tid</code>, otherwise it
     *         returns null
     */
    TazioTransaction getByTID(TID tid);

    /**
     * Adds a {@link Transaction} object to the <tt>TransactionsLog</tt> and
     * registers that transaction to the list of transactions whose lifecycle is
     * monitored by the log.
     * 
     * @param transaction
     *            The transaction to log
     */
    void logTransaction(TazioTransaction transaction);

    /**
     * Returns the number of rolled back transactions registered by the log.
     * 
     * @return the number of rolled back transactions registered by the log
     */
    int getNumRollbacks();

    /**
     * Returns the number of committed transactions registered by the log.
     * 
     * @return the number of rolled back transactions registered by the log
     */
    int getNumCommits();

    /**
     * Returns the number of active transactions currently registered on the
     * log.
     * 
     * @return the number of active transactions currently registered on the
     *         log.
     */
    int getNumActive();

}
